 ___          ___  ____             Front end 0.21  (15 Feb 2002)
/ __)_ __ _ _(__ \|  _ \_ __  __ _  spr2png   0.20  (15 Feb 2002)
\__ \ '_ \ '_|/_/|  __/ '_ \/ _' | draw2spr  0.06  (04 Aug 2001)
(___/ .__/_| (___)|_|  |_| |_\__  | png2spr   0.04  (04 Aug 2001)
    |_|                      (___/   Darren Salt, 1998-2001


This program allows conversion of sprites to PNG files and Draw and Artworks
files to sprite or PNG, and the conversion of PNG files to sprites.

See the end of this file for distribution conditions, credits and copyrights.

These programs require RISC OS 3.50 or later (or at least support for deep
sprites) and enough memory to store the image being processed in 32-bit RGB
colour.

If you plan to use this program to convert Artworks files, you should ensure
that you have the current release of AWViewer. This is available from
  http://www.mw-software.com/software/awmodules/awrender.html


The front end
=============

Conversion to PNG
-----------------

  Drag a sprite, Draw or Artworks file to the Spr2Png icon on the icon bar
  and a save box will appear. This contains the normal save box clutter and
  the following:

   [small sprite or PNG file icon]
      If the source is a Draw or Artworks file, this toggles the output type
      between sprite and PNG.

   Sprite
      The sprite source options.

     Image is RGBA
        If the sprite is 32-bit RGB colour, assume that it contains an alpha
        channel in the unused bits.

     Alpha channel is inverse
        Normally, the alpha channel scale ranges from 0 (transparent) to 255
        (opaque). This option tells Spr2Png that the reverse is true, ie.
        that 0 is opaque.

   Draw/AW
      The Draw and Artworks source options.

     Scale by
        This lets you arbitrarily scale the image by up to 10x along each
        axis. You may specify one scale factor in either field, or two
        independent scale factors; leave both fields blank for 1:1.
        Acceptable formats are simple, percentage and ratio; eg. to reduce to
        half size, you can use 0.5, 50% or 1:2.

     Artworks render level
        Controls how Artworks files are rendered. Useful values are:
          0  - outlines only
          5  - simple
          10 - normal
          11 - anti-aliased
        Note, however, that the image will be anti-aliased independently of
        the Artworks modules if an alpha channel is generated.

     Mask
     Alpha/blend
        These two options work together as follows:
          Mask  Alpha   Effect
           N     N      No mask, no anti-aliasing (but see AW render level).
           Y     N      Simple mask, no anti-aliasing (ditto).
           N     Y      Background blended, always anti-aliased.
           Y     Y      Full alpha channel, always anti-aliased.

   Misc
      Options which don't fit elsewhere.

     Verbose
        The more ticks, the more info will be displayed as Spr2Png is
        processing an image.

     Single task
        Normally, the back end is run in a taskwindow. With this ticked, it's
        run in a command box instead (but without the full screen redraw).
        (Only available if the output is to a PNG.)

   Output
      Various output options.

     Interlaced
        An interlaced PNG will be created, using ADAM7 (the standard 2D
        interlacing for PNG files).
        (Only available if the output is to a PNG.)

     Trim masked edges
        Remove transparent rows and columns from around the edges of the
        output image. If there's no mask, then the background colour (if one
        is specified) is treated as transparent.

        For Draw and Artworks files, when no mask is to be output, this
        removes the same edge rows and columns since they would otherwise
        have been masked out.

     Background
        If you want to set a default background colour, then enter it in the
        writeable field next to this label. The format is 24-bit hex BBGGRR
        (ie. black=0, desktop blue=994400, bright green=FF00, white=FFFFFF).
        If you click on the button to the right, a colour picker dbox will be
        opened.

     Gamma
        If you want the image to be displayed with gamma correction (provided
        that the program which is displaying it supports this), then enter a
        value here. The standard gamma value is 0.4545455 (more accurately,
        5/11).

   Reduce
      Image packing options, mostly affecting the actual image content.

     Try to make 8bit
        If possible, reduce the image to 8-bit colour.

       or less
          ... or less, if the number of colours permits. This is best used
          for images with long horizontal runs of the same colour; it can
          also be used for greyscale images, unless an alpha channel is
          present.

     sBIT chunk if true colour
        Counts the number of significant bits for the red, green and blue
        channels (for images which are or become 24 bit colour). This is
        recommended for 16bpp sprites.

     Extra greyscale checks
        Check whether only greys are used in an image. If so, then convert it
        to greyscale.

     Attempt to reduce mask
        If the mask is such that the image is fully opaque, ignore it.
        If the mask is simple and the resulting image would be 8-bit, use a
        spare palette entry for the mask.
        If the mask is such that the image is fully transparent... :-)

     Sort palette by usage
        Attempt to reduce the size of the PNG file by sorting the palette,
        most used colour first. The image is modified appropriately.

   Pack
      Compression options. These leave the image content intact.

     Filtering
        This lets you set the filtering options. Spr2Png will select from
        those chosen in order to best compress the image; see the libpng
        documentation for more details.

     Compression window
        This controls the maximum token size used by zlib (the compression
        code used by libpng). Higher values are almost always better (which
        is why the default is at the highest setting).

     Strategy
        The compression strategy. The default setting is normally the best,
        but 'filtered' (predictor) sometimes works better; if you want speed
        at the expense of size, then select Huffman.

     Compression level
        How hard spr2png will try to compress the image. It is usually best
        to leave this set to 9 (as much as possible, at the expense of
        speed).

  It's recommended that you set a background colour; see the section on
  browser display for more details.

  When you select somewhere to save the file (permanently), the Spr2Png back
  end will be run in a taskwindow. It can be a bit memory-hungry, although
  this is entirely down to the requirement (well, it's *much* easier to code
  it that way) that it has the whole image in memory before conversion to PNG
  is begun.


  The sprite file format
  ----------------------

  The sprite file contaning the image to be converted may contain one or two
  sprites.

  The first sprite is the image to be converted, and may be of any depth and
  can have a palette. It may have a mask.

  The second, if present, is used as an alpha channel. It must therefore have
  8bpp and a greyscale palette. (If only colours 0 and 255 are used - ie.
  fulll transparency and full visibility - then it is treated as a simple
  sprite mask.)

  If both sprites are present and the first one has a mask, then that mask is
  ignored.

  For <=8bpp sprites, palette packing is performed to reduce its size and try
  to improve the compression ratio. Normally, a logical colour (colour 0)
  will be allocated to the mask; if it is not possible to do this then the
  sprite will be scaled up to 24-bit (unless it's an 8bpp greyscale sprite)
  and be given an alpha channel.

  If an alpha channel is used, all non-greyscale sprites are scaled up to
  24-bit (15-bit sprites need to be scaled to 24-bit anyway).


Conversion from PNG
-------------------

  This requires RISC OS 3.50 or later; it normally generates 32-bit RGB
  colour sprites.

  Drag a PNG to the Spr2Png icon on the icon bar and a different save box
  will appear. This contains the normal save box clutter and the following:

   Background
      When ticked, then the image will be blended onto the given background
      colour, or if none is given, onto the background colour specified in
      the PNG (or white if it doesn't specify one). No alpha channel is
      generated, but any present information will be used unless "Ignore
      transparency" is ticked.

      When unticked, then an alpha channel will be generated unless "Ignore
      transparency" is ticked.

      The button to the right of the writeable field will open a colour
      picker dbox will be opened, from which you can select a colour;
      otherwise, the format is 24-bit hex BBGGRR (ie. black=0, desktop
      blue=994400, bright green=FF00, white=FFFFFF).

   Image gamma
      When ticked, either the supplied gamma value or the image's own gamma
      value is used. If no gamma value is present, then the default of
      0.4545455 (more accurately, 5/11) is used; this is also used if this
      option is unticked.

   Display gamma
      Either the supplied gamma value or the default of 2.2 is used. (Useful
      if you have several images to convert whilst retaining their own gamma
      values.)

      Together with image gamma, this provides full control over the rendered
      image's gamma correction.

   Ignore transparency
      When ticked, do not use the alpha channel or other available
      transparency information - the resulting image will not have an alpha
      channel, and it may look a bit strange.

   Create a separate mask
      When ticked, a separate grey-scale sprite is created for the alpha
      channel. (This option is implied for greyscale PNGs.)

   Try to reduce mask
      When ticked, if the alpha channel can be reduced to a simple mask (as
      normally used in RISC OS sprites), it will be (even if the above option
      is ticked). (Images with simple masks have this kind of mask anyway.)

   Alpha channel is inverse
      Normally, the alpha channel scale ranges from 0 (transparent) to 255
      (opaque). This option tells Spr2Png to create an inverse mask, ie.
      using 0 as opaque.


  PNGs with 16 bits per channel (ie. 48-bit RGB, 16-bit grey) will always be
  reduced to 8 bits per channel (ie. 24-bit RGB, 8-bit grey).


The back ends
=============

  spr2png
  -------

  <Spr2Png$Dir>.spr2png [options] SRC DEST

    SRC                  The source file (sprite or Draw).

    DEST                 The destination file (PNG).

  General options:

    -i,                  The image will be interlaced using the ADAM7 method
    --interlace          if this switch is present.

    -b,                  Specifies a suggested background colour of the form
    --background=COLOUR  &BBGGRR (as described above for the front end's save
                         box). If this is not present, no background colour
                         is defined.

    -g,                  Specifies the image's gamma correction value, ie.
    --gamma[=GAMMA]      that required to properly display it. Acceptable
                         values are 0 to 10; if 0 or no argument is given,
                         then the default of 0.5 (ie. no correction with a
                         device gamma of 0.5) is used.

  Sprite options:

    -a,                  If the sprite is 32-bit RGB colour, assume that it
    --alpha              contains an alpha channel in the unused bits.

    -n,                  If an alpha channel is supplied, then it is assumed
    --inverse-alpha      to be inverse, ie. 0 = opaque rather than
                         transparent.

  Draw and Artworks options (passed on to draw2spr):

    -S,                  Set the scale at which the drawing is rendered.
    --scale=X[,Y]        (See below.)

    -m,       -M,        These two options work together to determine the
    --no-mask --no-blend masking and blending. (See below.)

    -R,                  Artworks rendering control. (See below.)
    --render=LEVEL

    Other options which are passed on: --background --trim --verbose

  Packing options:

    -c,                  If the mask or alpha channel is unused (fully opaque
    --check-mask         image), ignore it. If it is 'simple' (only fully
                         transparent and opaque are used) and the image is
                         paletted, try to use a simple mask.
                         If the image is fully transparent...

    -t,                  Remove any transparent rows and columns from around
    --trim               the edges of the sprite. If there's no mask, then
                         the background colour is treated as transparent.

    -r,                  Attempt to ensure that the resulting PNG is
    --reduce             paletted. If the image has an alpha channel, it will
                         be used, resulting in paletted RGBA.

    -G,                  Perform extra greyscale tests - check whether only
    --check-grey         greys are used in an image and convert it to
                         greyscale if so.

    -p,                  If the PNG can be represented as 1, 2 or 4bpp (ie.
    --pack-pixels        is paletted and has sufficiently few palette
                         entries), then do so. This will usually /increase/
                         the size of the file. (Implies -r.)

    -s,                  Sort the palette such that the most often used
    --frequency-sort     entries occur first. This can reduce the size of the
                         resulting PNG file slightly.
                         (This does not happen for greyscale PNGs.)

  Compression options:

    -f,                  Specifies, using a comma-separated list FLTR, a list
    --filter=FLTR        of filter types to be tried when compressing the
                         image. These are 'none', 'sub', 'up', 'avg' and
                         'paeth'. (Alternatively, you may use just the first
                         letters, omitting the commas.)
                         These may improve compression for some types of
                         image; see the libpng documentation for more
                         details.

    -w,                  This controls the compression algorithm's maximum
    --window-bits=NUM    token length. It ranges between 9 and 15 bits;
                         higher values normally give better compression at a
                         speed cost. The default is 15.

    -z,                  This controls the compression strategy. Valid types
    --strategy=TYPE      are "default" (0), "filtered" (1) and "huffman" (2);
                         they can be referred to by number or name. Default
                         is normally best; Huffman is normally worst, but is
                         the fastest.

    -0                   No compression.
    -1    --fast         Minimal compression; fast.
    -9    --best         Maximum compression; slow. This is the default.
                         Other values between 1 and 9 may be used.

  General options:

    -v,                  Be (more) verbose.
    --verbose


  draw2spr
  --------

  <Spr2Png$Dir>.draw2spr [options] SRC DEST

    SRC                  The source file (sprite or Draw).

    DEST                 The destination file (PNG).

    -s,                  Set the scale at which the drawing is rendered.
    --scale=X[,Y]        This may be up to 10x along each axis; you may
                         specify one or two scaling factors.
                         Acceptable formats are simple, percentage and ratio.

    -t,                  Remove any transparent rows and columns from around
    --trim               the edges of the sprite. If no mask is to be output,
                         then remove those same rows and columns since they
                         would otherwise have been masked out.

    -b,                  Specifies a background colour of the form &BBGGRR
    --background=COLOUR  (see above). If none is specified, then white is
                         used; however, a mask is always generated.

    -m,       -M,        These two options work together to determine the
    --no-mask --no-blend masking and blending as follows:
              --no-alpha   -m -M  Effect
                           n  n  No mask, no anti-aliasing (see -R).
                           Y  n  Simple mask, no anti-aliasing (ditto).
                           n  Y  Background blended, always anti-aliased.
                           Y  Y  Full alpha channel, always anti-aliased.

    -n,                  If an alpha channel is created, then it is inverted,
    --inverse-alpha      ie. 0 = opaque rather than transparent.

    -r,                  Artworks rendering control. The default is 11.0.
    --render=LEVEL       (See the rendering level option in the front end.)

    -v,                  Be (more) verbose.
    --verbose


  png2spr
  -------

  <Spr2Png$Dir>.png2spr [options] SRC DEST

    -b,                  Use either the given colour, the image's colour or
    --background[=BGND]  white for the rendered PNG. The format is &BBGGRR
                         (as described above). If this is not present, then
                         an alpha channel will be generated (if no -M); else
                         the image will instead be background blended.
                         (Overrides -s and -c.)

    -g,                  Use either the given image gamma, the image's own
    --gamma[=GAMMA]      gamma or 1/2.2. If not present, then the default of
                         1/2.2 is used.

    -d,                  Use the given display gamma correction, else 2.2.
    --display-gamma=GAMMA

    -M,                  Ignore transparency information, and don't generate
    --no-alpha           an alpha channel. (Overrides -s and -c.)

    -s,                  Generate a greyscale sprite for the alpha channel.
    --separate-alpha     (Implied for greyscale PNGs.)

    -c,                  If the alpha channel consists of fully transparent
    --check-mask         and fully opaque, create a simple mask instead (and
                         not a separate alpha channel).
                         (Implied for paletted or greyscale PNGs with simple
                         transparency - ie. with a tRNS chunk.)

    -n,                  If the PNG contains an alpha channel (and it isn't
                         ignored or optimised out) then it is inverted, ie.
    --inverse-alpha      ie. 0 = opaque rather than transparent.


  For all three programs, those short options which do not take arguments may
  be combined, eg. "-arfns" == "-a -r -fns". Those which do may be appended
  to the end of such a list.

  They also recognise --help and --version.




Sprite conversion information
-----------------------------

  Greyscale images are recognised by the standard 256-entry greyscale
  palette.

  Colour depth expansion is always performed from <8 bit to 8 bit, and from
  15 bit RGB or 32 bit CMYK to 32 bit RGB (the packed 24 bit RGB and JPEG
  formats are not handled). Further expansion will be performed from 8 bit
  colour to 32 bit RGB where:
   - a full alpha channel is used and cannot be reduced to a simple mask; or
   - there is a simple mask and all 256 colours are present in the image. (As
     in the GIF format, a simple mask occupies one logical colour.)

  Then, if a background colour is specified:
   - For 8 bit colour images using all 256 colours and with no mask, the
     nearest available palette entry will be chosen. Otherwise, a spare
     palette entry will be used.
   - For greyscale images, the grey nearest the specified RGB value will be
     used.
   - For 32 bit RGB images, no conversion is necessary; the colour is used as
     is.

  Some of this is controlled by various command line switches.


Draw and Artworks conversion information
----------------------------------------

  Draw and Artworks files are normally plotted in 32-bit RGB colour at 4
  times the specified scale) and are then reduced by a factor of 4 using a
  simple anti-aliasing algorithm. If a simple mask is requested, then they
  are simply plotted at the specified scale and no reduction is performed.

  There is no need to re-render the image, since it's possible to use the
  unused bits in each pixel to determine which are left untouched by the
  rendering process; this gives the mask. If an alpha channel is required,
  this is reduced as described above.

  Converting a large (in terms of the dimensions of the rendered image) file
  will use a lot of memory, although the back end can render Draw files in
  strips when memory is short.

  In Artworks files: deep sprites, text areas and replicated objects won't be
  rendered. This is a limitation of the Artworks renderer modules.


PNG conversion information
--------------------------

  Deep sprites may be created.


Risc PC
-------

  Both spr2png and draw2spr prefer to use a dynamic area. The main advantage
  of doing so is in task-switching speed (although this is much less of an
  issue in RISC OS 3.8 and later). You'll notice it most when converting Draw
  and Artworks files.


Browser display of PNGs
=======================

  Some browsers have problems with alpha channels when no background colour
  is specified for the image. The following is from my experience of various
  browsers:

   Arcweb 1.92
      Its somewhat basic PNG display code will default to something
      potentially very inappropriate (typically a black background).

   Browse 2.07
      No problems at all.

   Fresco 1.78F
      It totally ignores the alpha channel in paletted RGBA; otherwise, it
      uses a binary cutoff. (It has also been known to crash while loading
      several images.)

   Internet Explorer 4.01
      Seems to dislike PNGs...

   Internet Explorer 5
      It does not appear to be consistent in how it handles background
      colours across colour depths.

   Netscape Navigator 4.05
      It will render on a rectangle of the image's given background colour;
      if none is given, the alpha channel is ignored.
      (I'm informed that Mozilla alphas, as of 28 Aug 1999, do much better;
      but the screenshot which I have says that a cutoff point is used.)

  <URL:http://www.youmustbejoking.demon.co.uk/pngtest/> will show you how
  your browser copes with various PNGs with various options. (This is not an
  exhaustive test; it only tests colour depths and bKGD chunks.)


Distribution
============

This program and its associated files are freeware. This archive may be
distributed in unmodified form only on any ftp or web site (in the latter
case, it is required that you provide an obvious link to the "home link" URL,
given in the Contact section of this file).

Freeware usage
--------------

This covers any software which is distributed freely, irrespective of media
charges (which should be minimal).

Permission to distribute Spr2Png, in part or in whole, is granted on
condition that any modifications to the software are made available to me and
that an obvious link to the "home link" URL (given in the Contact section of
this file) is provided.

Commercial usage
----------------

This covers any software for which a specific charge is made for either
licence or support.

Permission to distribute Spr2Png, in part or in whole, with commercial
software may be given upon request. The minimum charge is a free copy of the
complete package with free support and upgrades.

Other usage
-----------

Contact me.


Credits & copyrights
====================

  libpng (the PNG library):
    Glenn Randers-Pehrson, Greg Roelofs, Guy Eric Schalnat and others
    <URL:ftp://ftp.freesoftware.com/pub/png/>

  zlib (the compression library):
    Jean-loup Gailly & Mark Adler
    <URL:ftp://ftp.cdrom.com/pub/infozip/zlib/>

  Draw to sprite:
    modified from Peter Hartley's Draw rendering code in InterGif
    <URL:http://utter.chaos.org.uk/~pdh/software/intergif.htm>

  Artworks to sprite:
    with help from Rob Davison and AWViewer.


Contact
-------

  Home page: <URL:http://www.youmustbejoking.demon.co.uk/>
  Home link: <URL:http://www.youmustbejoking.demon.co.uk/progs.graphics.html#spr2png>
  Email:     <URL:mailto:ds@youmustbejoking.demon.co.uk>
